//! # 文档注释
//! - '//!' 是文档注释
//! - '///' 是函数,类,枚举,等等的注释
//!
//!
//!
//!
//!

#![allow(unused)]
#![allow(clippy::mixed_attributes_style)]

/// add 函数注释
///
/// fn 在文档里显示为 `Functions`
fn add() {
    // 函数内部采用普通注释
    //
    //   - 普通注释
    // /  - 外部行文档型注释 (以 3 个 `///` 开始)
    // // - 普通注释

    /*   - 普通注释 */
    /*** - 普通注释 */
}

/// main 函数注释
///
/// fn 在文档里显示为 `Functions`
fn main() {}

/// 结构体Person 注释,
/// struct 在文档里显示为 `Structs`
struct Person {}

/// mod outer_module 注释,
/// mod 在文档里显示为 `Modules`
pub mod outer_module {
    //!  - 内部行文档型注释
    //!! - 仍是内部行文档型注释 (但是这样开头会更具强调性)

    /*!  - 内部块文档型注释 */
    /*!! - 仍是内部块文档型注释 (但是这样开头会更具强调性) */

    //   - 普通注释
    ///  - 外部行文档型注释 (以 3 个 `///` 开始)
    //// - 普通注释

    /*   - 普通注释 */
    /**  - 外部块文档型注释 (exactly) 2 asterisks */
    /*** - 普通注释 */

    pub mod inner_module {}

    pub mod nested_comments {
        /* 在 Rust 里 /* 我们可以 /* 嵌套注释 */ */ */

        // 所有这三种类型的块注释都可以包含或嵌套在任何其他类型的
        // 注释中：

        /*   /* */  /** */  /*! */  */
        /*!  /* */  /** */  /*! */  */
        /**  /* */  /** */  /*! */  */
        pub mod dummy_item {}
    }

    pub mod degenerate_cases {
        // 空内部行文档型注释

        // 空内部块文档型注释

        // 空行注释
        //

        // 空外部行文档型注释

        // 空块注释
        /**/

        pub mod dummy_item {}

        // 空的两个星号的块注释不是一个文档块，它是一个块注释。
        /***/
    }

    /* 下面这个是不允许的，因为外部文档型注释需要一个
    接收该文档的程序项 */

    /// 我的程序项呢?
    mod boo {}
}
